tiny-invariant

What is tiny-invariant?

The tiny-invariant package is a utility that allows developers to enforce conditions throughout their code. When a condition fails, it throws an error with a specified message. This is particularly useful for catching programming errors at runtime and ensuring that code behaves as expected. It's designed to be minimalistic and efficient, making it suitable for both development and production environments.

What are tiny-invariant's main functionalities?

Invariant Checking

This feature allows you to check if a condition is true. If the condition is false, it throws an error with the provided message. This is useful for validating assumptions in your code. For example, checking if a required function argument is provided.

invariant(condition, message);

Other packages similar to tiny-invariant

assert

The 'assert' module is a part of Node.js core and provides a simple set of assertion tests. It is similar to tiny-invariant in that it can be used to test invariants and throw errors when conditions fail. However, 'assert' is more comprehensive, offering a wider range of assertion types, such as deep equality checks and strict equality checks. Unlike tiny-invariant, 'assert' is built into Node.js and does not need to be installed separately.

invariant

The 'invariant' package is another npm package that provides similar functionality to tiny-invariant. It allows developers to enforce invariants by throwing errors when conditions are not met. The main difference between 'invariant' and tiny-invariant is in their size and dependencies. 'invariant' might be slightly larger and could have more dependencies, making tiny-invariant a more lightweight choice for projects where package size is a concern.

README

tiny-invariant 🔬💥

A tiny invariant alternative.

What is invariant?

An invariant function takes a value, and if the value is falsy then the invariant function will throw. If the value is truthy, then the function will not throw.

import invariant from 'tiny-invariant';

invariant(truthyValue, 'This should not throw!');

invariant(falsyValue, 'This will throw!');
// Error('Invariant violation: This will throw!');

You can also provide a function to generate your message, for when your message is expensive to create

import invariant from 'tiny-invariant';

invariant(value, () => getExpensiveMessage());

Why tiny-invariant?

The library: invariant supports passing in arguments to the invariant function in a sprintf style (condition, format, a, b, c, d, e, f). It has internal logic to execute the sprintf substitutions. The sprintf logic is not removed in production builds. tiny-invariant has dropped all of the sprintf logic. tiny-invariant allows you to pass a single string message. With template literals there is really no need for a custom message formatter to be built into the library. If you need a multi part message you can just do this:

invariant(condition, `Hello, ${name} - how are you today?`);

Type narrowing

tiny-invariant is useful for correctly narrowing types for flow and typescript

const value: Person | null = { name: 'Alex' }; // type of value == 'Person | null'
invariant(value, 'Expected value to be a person');
// type of value has been narrowed to 'Person'

API: (condition: any, message?: string | (() => string)) => void

• condition is required and can be anything
• message optional string or a function that returns a string (() => string)

Installation

# yarn
yarn add tiny-invariant

# npm
npm install tiny-invariant --save

Dropping your message for kb savings!

Big idea: you will want your compiler to convert this code:

invariant(condition, 'My cool message that takes up a lot of kbs');

Into this:

if (!condition) {
  if ('production' !== process.env.NODE_ENV) {
    invariant(false, 'My cool message that takes up a lot of kbs');
  } else {
    invariant(false);
  }
}

• Babel: recommend babel-plugin-dev-expression
• TypeScript: recommend tsdx (or you can run babel-plugin-dev-expression after TypeScript compiling)

Your bundler can then drop the code in the "production" !== process.env.NODE_ENV block for your production builds to end up with this:

if (!condition) {
  invariant(false);
}

• rollup: use rollup-plugin-replace and set NODE_ENV to production and then rollup will treeshake out the unused code
• Webpack: instructions

Builds

• We have a es (EcmaScript module) build
• We have a cjs (CommonJS) build
• We have a umd (Universal module definition) build in case you needed it

We expect process.env.NODE_ENV to be available at module compilation. We cache this value

That's it!

🤘